<?xml version='1.0'?><!DOCTYPE html PUBLIC><html xmlns='http://www.w3.org/1999/xhtml'>
  <head>
    <title>jMock - Stubs, Expectations and the Dispatch of Mocked Methods</title>
    <link href='/jmock.css' title='Navigation View' rel='stylesheet' type='text/css' media='screen' />
    <link href='/print.css' title='Print Preview' rel='alternate stylesheet' type='text/css' media='screen' />
    <link href='/print.css' rel='stylesheet' type='text/css' media='print' />
    <meta content='text/html; charset=iso-8859-1' http-equiv='Content-Type' /><meta name='generator' content='amaya 8.5, see http://www.w3.org/Amaya/' />
  </head>

  <body>
    <div id='banner'>
      <a href='/index.html'><img src='/logo.gif' id='logo' alt='jMock' /></a>
    </div>

    

    
      <div class='Content2Column' id='center'>
        <div id='content'>
          <h1 class='FirstChild'>Stubs, Expectations and the Dispatch of Mocked Methods</h1><p>In jMock, stubs and expectations are basically the same thing. A stub is just an
expectation of zero or more invocations. The <code>stubs()</code>
method is syntactic sugar to make the intent of the test more explicit.</p><p>When a method is invoked on a mock object, the mock object searches
through its expectations from newest to oldest to find one that matches the
invocation. After the invocation, the matching expectation might stop matching
further invocations. For example, an <code>expects(once())</code> expectation only matches
once and will be ignored on future invocations while an <code>expects(atLeastOnce())</code>
expectation will always be matched against invocations.
</p><p>This scheme allows you to:</p><ul>
  <li>Set up default stubs in your the <code>setUp</code> method of your test class
  and override some of those stubs in individual tests.</li>
  <li>Set up different &quot;once&quot; expectations for the same method with different action per
  invocation.  However, it's better to use the <code>onConsecutiveCalls</code>
  method to do this, as described below.</li>
</ul><p>However, there are some possible &quot;gotchas&quot; caused by this scheme:</p><ul>
  <li>if you create an expectation and then a stub for the same method, the
    stub will always override the expectation and the expectation will never
    be met.</li>
  <li>if you create a stub and then an expectation for the same method, the
    expectation will match, and when it stops matching the stub will be used
    instead, possibly masking test failures.</li>
  <li>if you create different expectations for the same method, they will be
    invoked in the opposite order than that in which they were specified, rather
    than the same order.</li>
</ul><p>The best thing to do is <em>not</em> set up multiple expectations and
stubs for the same method with exactly the same matchers. Instead, use the
<tt><code>onConsecutiveCalls</code></tt> method to create multiple actions
for a method. For example:</p><div class='Java Source'>
<pre>mock.expects(atLeastOnce()).method(m).with(...)
   .will( onConsecutiveCalls(
       returnValue(10),
       returnValue(20),
       throwException(new IOException("end of stream")) ) );</pre>
</div><p>If you want to specify more complex ordering or order invocations across different
mock objects, use the <code>after</code> method to explicitly define a total or
partial ordering of invocations.</p>
        </div>
	    <div class='Meta'>
	      <p><a href='http://cvs.jmock.codehaus.org/jmock/website/content/dispatch.html'>Document History</a></p>
	    </div>
      </div>
    

    <div class='SidePanel' id='left'>
      <div class='MenuGroup'>
        <h1><a href='/download.html'>Software</a></h1>
        <ul>
          <li><a href='/download.html'>Download</a></li>
          <li><a href='/repository.html'>Anonymous CVS Access</a></li>
          <li><a href='/license.html'>Project License</a></li>
          <li><a href='/CHANGELOG'>Change Log</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1><a href='/docs.html'>Documentation...</a></h1>
        <ul>
          <li><a href='/getting-started.html'>Getting Started</a></li>
          <!-- <li><a href="">Frequently Asked Questions</a></li> -->
          <li><a href='/docs/javadoc/index.html' target='jmock-javadoc'>JavaDocs</a></li>
          <li><a href='http://www.mockobjects.com'>More about Mock Objects</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1>User Support</h1>
        <ul>
          <li><a href='/mailing-lists.html'>Mailing Lists</a></li>
          <li><a href='http://jira.codehaus.org/secure/BrowseProject.jspa?id=10336'>Issue Tracker</a></li>
          <li><a href='/news-rss2.xml'>News Feed (RSS 2.0)</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1><a href='/development.html'>Development...</a></h1>
        <ul>
          <li><a href='/how-to-contribute.html'>How to Contribute</a></li>
          <li><a href='/team.html'>Development Team</a></li>
        </ul>
      </div>

      <div class='MenuGroup'>
        <h1>Related Sites</h1>
        <ul>
          <li><a href='http://www.mockobjects.com'>Mock Objects</a></li>
          <li><a href='http://www.junit.org'>JUnit</a></li>
          <li><a href='http://www.nmock.org'>nMock</a></li>
          <li><a href='http://www.codehaus.org'>Project hosted by Codehaus</a></li>
        </ul>
      </div>
    </div>

    
  </body>
</html>